Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Correlations API #101

Merged
merged 9 commits into from
May 7, 2020
Merged

Add Correlations API #101

merged 9 commits into from
May 7, 2020

Conversation

jtescher
Copy link
Member

This adds an implementation of the Correlations API which is used to annotate telemetry, adding context and information to metrics, traces, and logs. It is an abstract data type represented by a set of name/value pairs describing user-defined properties.

Example:

let propagator = CorrelationContextPropagator::new();
// can extract from any type that impls `Carrier`, usually an HTTP header map
let cx = propagator.extract(&headers);

// Iterate over extracted name / value pairs
for (name, value) in cx.correlation_context() {
  // ...
}

// Add new correlations
let cx_with_additions = cx.with_correlations(vec![Key::new("server_id").u64(42)]);

// Inject correlations into http request
propagator.inject_context(&cx_with_additions, &mut headers);

Resolves #62

This provides an implementation of the [Context API
Spec](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/context.md).
A context is a propagation mechanism which carries execution-scoped values
across API boundaries and between logically associated execution units.
Cross-cutting concerns access their data in-process using the same shared
`Context` object.

It is implemented as an immutable thread-local collection of heterogeneous
values that can be inserted and retrieved by their type. A thread's current
context can be assigned via the `attach` method. The previous context is
restored as the current context when the resulting context guard is dropped,
allowing precise control and nesting of active context scopes.
This change moves the storage and management of active spans from the
current `SpanStack` implementation to the new `Context` api, as well as
updating the propagation APIs to inject and extract contexts to remain
compatible with the tracers. This has some breaking API changes to the
way tracing is currently done, most notable is that the `Tracer`'s
`start` method no longer requires an optional parent span context as
that can now be provided by the current context.

The previous tracing api was:

```rust
// extract
let remote_span_context = propagator.extract(&carrier);

// start
let parent = tracer.start("parent", Some(remote_context));
tracer.mark_span_as_active(&parent);

// nest (note: `Some(parent.get_context())` and `None` had the same effect here)
let child = tracer.start("child", None);
tracer.mark_span_as_active(&child)

// inject
propagator.inject(child.get_context(), &mut carrier);

// Marking as inactive was required and error-prone
trace.mark_span_as_inactive(&child);
trace.mark_span_as_inactive(&parent);
```

And the new API is:

```rust
// extract
let _attach = propagator.extract(&carrier).attach();

// start
let parent = tracer.start("parent");
let _parent_active = tracer.mark_span_as_active(parent);

// start
let child = tracer.start("child");
let _child_active = tracer.mark_span_as_active(parent);

// inject
propagator.inject(&mut carrier)
```

Additional changes to facilitate the switch:

* `tracer.with_span` now accepts a span for naming consistency and
managing the active state of a more complex span (likely produced by a
builder), and the previous functionality that accepts a `&str` has been
renamed to `in_span`, both of which now yield a context to the provided
closure.
* The `Instrument` trait has been renamed to `FutureExt` to avoid
clashing with metric instruments, and accepts contexts.
* `TracerGenerics` methods have been folded in to the `Tracer` trait so
the trait is no longer needed 🎉 .
* A `TraceContextExt` trait provides methods for working with trace data
in a context. Most notably `context.span()` returns a `&dyn api::Span`
reference, and `Context::current_with_span(span)` creates a clone of the
current context with the span added.
* Span's managing their own active state is no longer needed 🎉.
* Span's `get_context` method has been renamed to `span_context` to
avoid the ambiguity.
@jtescher jtescher added the S-blocked-spec Status: Blocked on open or unresolved spec label Apr 26, 2020
@jtescher jtescher requested a review from a team April 26, 2020 20:30
This adds an implementation of the [Correlations
API](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/correlationcontext/api.md)
which is used to annotate telemetry, adding context and information to
metrics, traces, and logs. It is an abstract data type represented by a
set of name/value pairs describing user-defined properties.

Example:

```rust
let propagator = CorrelationContextPropagator::new();
// can extract from any type that impls `Carrier`, usually an HTTP header map
let cx = propagator.extract(&headers);

// Iterate over extracted name / value pairs
for (name, value) in cx.correlation_context() {
  // ...
}

// Add new correlations
let cx_with_additions = cx.with_correlations(vec![Key::new("server_id").u64(42)]);

// Inject correlations into http request
propagator.inject_context(&cx_with_additions, &mut headers);
```

Resolves #62
@jtescher jtescher removed the S-blocked-spec Status: Blocked on open or unresolved spec label May 7, 2020
@jtescher jtescher merged commit e5f5860 into open-telemetry:master May 7, 2020
@jtescher jtescher deleted the correlation-context branch May 7, 2020 01:44
cijothomas pushed a commit to cijothomas/opentelemetry-rust that referenced this pull request Sep 7, 2024
Co-authored-by: Lalit Kumar Bhasin <lalit_fin@yahoo.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add Layer for Context Propagation
2 participants